=begin pod

=TITLE role Buf

=SUBTITLE Mutable buffer for binary data

    role Buf[::T] does Blob[T] { ... }

A C<Buf> is a mutable sequence of (usually unsigned) integers.

    my $b = Buf.new(1, 2, 3);
    $b[1] = 42;

=head1 Methods

=head2 method subbuf-rw

    method subbuf-rw($from, $length?)

A mutable version of C<subbuf> that returns a L<Proxy|/type/Proxy> functioning as a
writable reference to a part of a buffer. Its first argument, C<$from>
specifies the index in the buffer from which a substitution should occur, and
its last argument, C<$length> specifies how many elements are to be replaced.

For example, to replace one element at index 3 with two elements, C<100> and C<101>:

    my Buf $b .= new(0..5);
    $b.subbuf-rw(3,1) = Buf.new(100, 101);
    say $b.perl;   # OUTPUT: «Buf.new(0,1,2,100,101,4,5)␤»

=head2 routine subbuf-rw

    sub subbuf-rw(Buf:D $buf, $from, $length?)

Returns a writable reference to a part of a buffer. Similar to the C<subbuf-rw> method:

    my Buf $b .= new(1,2,3);
    subbuf-rw($b,2,1) = Buf.new(42);
    say $b.perl;   # OUTPUT: «Buf.new(1,2,42)␤»

=head2 method reallocate

    method reallocate($elems)

Change the number of elements of the C<Buf>.  The C<Buf> will be made larger if
the specified value is larger than the current number of elements.  The value of
newly created elements is undetermined and should thus not be relied upon.  It
returns the altered C<Buf>.

    my Buf $b .= new(^10);
    $b.reallocate(5);
    say $b.perl;  # OUTPUT: «Buf.new(0,1,2,3,4)␤»

=head2 method push

    method push( $elems )

Adds elements at the end of the buffer

     my @φ =  1,1, * + * … ∞;
     my $bú = Buf.new( @φ[^5] );
     $bú.push( @φ[5] );
     say $bú.perl; # OUTPUT: «Buf.new(1,1,2,3,5,8)»

=head2 method pop

    method pop()

Extracts the last element of the buffer

    =for code :skip-test
    say $bú.pop(); # OUTPUT: «8»
    say $bú.perl; # OUTPUT: «Buf.new(1,1,2,3,5)»

=head2 method append

    method append( $elems )

Appends at the end of the buffer

    =for code :skip-test
    $bú.append( @φ[5..10] );
    say $bú.perl; # OUTPUT: «Buf.new(1,1,2,3,5,8,13,21,34,55,89)»

=head2 method prepend

    method prepend( $elems )

Adds elements at the beginning of the buffer

    =for code :skip-test
    $bú.prepend( 0 );
    say $bú.perl; # OUTPUT: «Buf.new(0,1,1,2,3,5,8,13,21,34,55,89)»

=head2 method shift

    method shift()

Takes out the first element of the buffer

    =for code :skip-test
    $bú.shift();
    say $bú.perl; # OUTPUT: «Buf.new(1,1,2,3,5,8,13,21,34,55,89)»

=head2 method unshift

    method unshift()

Adds elements at the beginning of the buffer

    =for code :skip-test
    $bú.unshift( 0 );
    say $bú.perl; # OUTPUT: «Buf.new(0,1,1,2,3,5,8,13,21,34,55,89)»

=head2 method splice

    method splice( Buf:D: $start = 0, $elems?, *@replacement --> Buf)

Substitutes elements of the buffer by other elements

    =for code :skip-test
    $bú.splice:  0, 3, <3 2 1>;
    say $bú.perl; # OUTPUT: «Buf.new(3,2,1,2,3,5,8,13,21,34,55,89)»

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
